docs(ai): no gemini fallback, one Ollama address for every read, --agent target dirs (forge-cli#852) - #205

Companion to forge-cli #852, the follow-ups to forge-cli #850. #204 documented #850 and is merged; this PR updates the same pages for #852.

Draft until review. forge-cli #852 merged at 08:26Z as 3900c45f. The new sentences therefore carry *On forge-cli main, not yet in a release ([forge-cli #852](...)).*, as #850's do. Sentences that start "Before #852" describe main between #850 and #852. No release shipped that state, so they can go at the next pin bump if #850 and #852 ship together.

Checked against these forge-cli commits:

• cbf1fc61, #852's head at the time. The final head 3166bde0 only adds a test to tests/test_ollama_host.py, and the squash 3900c45f has the same tree as 3166bde0.
• 28a1f2e2 (main before #852), for "Before #852".
• The pinned 0.28.0, and 0.27.0 for the fluid ai test note.

What changed

• No gemini fallback. With nothing that names a provider, forge stops with copilot_no_llm_provider. advanced/production-troubleshooting.md gets a "No LLM provider is selected" section: the four messages, their causes and the catalog's suggestions. The error's docs link lands on that page without an anchor. advanced/error-codes.md gets the catalog entry. llm-providers.md, cli/doctor.md, cli/ai.md and environment-variables.md drop "falls back to gemini" and say which settings name a provider.

• One Ollama address for every read. A new "One address for every Ollama read" section in llm-providers.md covers the following:

  • OLLAMA_HOST may name any machine for the probe, the default-model pick and fluid ai setup.
  • A stated endpoint drives the model pick, the model check and each --tiered stage.
  • --llm-endpoint gpu-box means http://gpu-box:11434.
  • user:password@ is sent as basic auth, shown masked, and saved only with FLUID_ALLOW_PLAINTEXT_AI_SECRETS.
  • The environment's OLLAMA_HOST wins over the saved address.

  The sentences that said these reads stay on localhost are replaced in cli/ai.md, litellm-backend.md and network-safety.md.

• fluid ai test --endpoint takes an Ollama address on any host. The exit-2 row of the exit-code table now lists the endpoints it refuses. The model check asks --endpoint, so the page's example exits 5.

• fluid forge --agent reports a contract written to any --target-dir (cli/forge.md).

• upgrading.md gets a short #852 subsection under "On forge-cli main since 0.28.0", including the LlmProvider.list_available_models(..., endpoint=) keyword. No page documents provider plugins, so that is the only place for it.

• Stale warning removed. The 0.18.1 fluid ai test crash ("name 'detect_ollama_available' is not defined") was fixed in 0.28.0 (forge-cli #839). The warning in cli/ai.md and production-troubleshooting.md now says so.

• Wrong on 0.28.0 too, fixed in passing. Neither sentence carries a marker:

  • environment-variables.md said FLUID_LLM_API_KEY is used "when no provider-specific key is set". In fact it wins over the provider's own key.
  • cli/forge.md said forge data-model --llm-model alone uses the saved provider, else ollama. In fact it does not read the saved choice: it uses a local Ollama that answers, else gemini.

• The saved-provider condition. llm-providers.md now says that a run with --non-interactive (which --agent sets) skips the provider fluid ai setup saved. The inline setup is gated on that flag, not on a terminal.

Checks run locally

Run with Python 3.11 and data-product-forge==0.28.0 from pypi.org/simple, with FORGE_CLI_CHANGELOG set to forge-cli main's CHANGELOG.md:

• check_cli_docs.py: exit 0. All 1382 fluid invocations match, and the marker sweep is OK. No flag_oracle_ok entry is needed.
• gen_contract_reference.py --check and check_providers.py: exit 0.
• npm ci && npm run docs:build: exit 0. node scripts/check-dist-links.mjs is clean, and every new anchor is in dist/.
• Base-prefix check: OK.
• lychee-source, offline, over CI's route mirror: 0 errors; the canaries behave (0 and 2).

How the claims were checked

Every sentence was checked by running the CLI on forge-cli cbf1fc61, 28a1f2e2, v0.28.0 and v0.27.0, in an isolated environment:

• a scratch HOME and a null keyring;
• no agent CLIs on PATH;
• a dead proxy hiding the local Ollama;
• a stub Ollama on the LAN address, for the non-local reads, the model picks and basic auth.

The new test_forge_agent_mode.py cases pass on cbf1fc61 (21 passed) and fail on main (4 failed).

The first pass found 7 imprecise sentences and 3 that were wrong or stale outside the change. The re-check confirmed all fixed, and found two cells where the #852 marker trailed the #852 text; in those cells the markers now come before the text they mark.

Left as is on purpose: network-safety.md's "Defaults that changed in v0.8.3" row still says "Localhost only". It is a history row, and its Override cell carries the #850 and #852 notes.